====== LESS CSS Support in DokuWiki ======

This is available since release 2013-12-08 "[[:old_changes#release_2013-12-08_binky|Binky]]".

LESS is a dynamic stylesheet language that compiles to CSS. It offers new mechanisms like variables, nesting, mixins, operators and functions when writing stylesheets.

DokuWiki's [[CSS]] dispatcher includes a PHP-based LESS parser which means you can use the full advantage of this dynamic CSS preprocessing in your [[template]] and [[plugin]] styles. Of course this is completely optional you can also write plain old CSS.

LESS statements are parsed in ''.css'' and in ''.less'' files.

===== LESS Language Constructs  =====

Please refer to the official [[https://github.com/MarcusSchwarz/lesserphp/blob/master/docs/docs.md|lesserphp documentation]](([[https://lesscss.org/#docs|lesscss.org documentation]] is **not** the right manual for DokuWiki )) to learn about the language itself. We're using [[https://github.com/MarcusSchwarz/lesserphp|lesserphp]] as a parser so any restrictions of that library apply (eg. you can't use JavaScript expressions).

===== Style Guide =====

When using LESS please keep the following things in mind:

  * **Use nesting sparsely**. Nesting deeper that 3 or 4 levels usually isn't needed and does not improve readability and might even affect selector performance
  * **Prefix your mixins and variables**. When you define your own mixins and variables try to avoid common names that might clash with other templates or plugins. Just as you would with your classes and IDs.

===== Accessing style.ini placeholders =====

[[style.ini]] placeholders are available in your styles as LESS variables, prefixed with ''%%@ini_%%'' and with the ''%%__%%'' removed.

E.g. the ''%%__background__%%'' placeholder becomes ''%%@ini_background%%'' in your LESS styles.

===== Version of lesserphp =====

At the moment (current date: 2021-12-30) the newest version of lesserphp is 0.5.5, which is included in DokuWiki "[[:changes#release_2020-07-29a_hogfather|Hogfather]]". Although the publication date of version 0.5.5 is March 10 2021 ([[https://leafo.net/lessphp/changelog.html|Changelog]]) there has been only mostly PHP compatibility changes since 2016. That means some features of the current less.js (which is the primary less-compiler) are not supported by this version.

Nevertheless you can achieve advanced technics, but less convenient. As shown in the following realization of an "IF-Statement", which is capable to include or exclude several CSS-rules at once.


===== How to realize an “IF-Statement”? =====

This LESS-code:

<code css>
@my-option: false;

.my-optional-style() when (@my-option = false) {
    #main_body { background-color: red; }
    p { color: green; }
}

.my-optional-style() when (@my-option = true) {
    #main_body { background-color: green; }
    p { color: black; }
}

.my-optional-style();
</code>

compiles to this CSS-code:

<code css>
#main_body {
  background-color: red;
}
p {
  color: green;
}

</code>

===== Insert Unparsed Code =====

  * A trick to insert (nearly) every unparsed code in LESSPHP: [[issue>2254#issuecomment-386814503|Github/dokuwiki/issues#2254 (comment)]]
  * And if you use an import of a css file [[https://github.com/dokuwiki/dokuwiki/issues/3735#issuecomment-1207289682|it is not processed as LESS]].

FIXME Add code example here
===== Caveats =====

Because all CSS has to pass through the LESS parser, we're a bit more strict on valid CSS. If your plugin uses invalid CSS it will likely throw an error now. A list of currently known problems is available at [[devel:less-errors|Less CSS Errors]].